'.\" t
.TH "cldaemon" "1M" "Jun 22, 2006" "1\&.2\&.0"
.SH NAME
cldaemon \- Linuxha.net Cluster Daemon

.SH SYNOPSIS
.TS
l.
cldaemon \fB--form\fP [\fB--verbose\fP] [\fB--file\fP \fIpath\fP] [\fB--detach\fP] [\fB--timeout\fP \fINN\fP]
         [\fB--force\fP] [\fB--logcmd\fP] [\fB--nolocking\fP] [\fB--nochecksums\fP]
         Form a new cluster

cldaemon \fB--join\fP [\fB--verbose\fP] [\fB--file\fP \fIpath\fP] [\fB--detach\fP] [\fB--timeout\fP \fINN\fP]
         [\fB--force\fP] [\fB--logcmd\fP] [\fB--nolocking\fP] [\fB--nochecksums\fP]
         Join an existing cluster

cldaemon \fB-?\fP
         Show brief usage information
.TE

.SH DESCRIPTION
The \fIcldaemon(1M)\fP is the key process for Linuxha.net to function 
currently. 
This process must be running on both nodes in the cluster to ensure they 
handle events affecting the availability of the applications that 
are being monitored.

The command is typically run in the 'form' mode - the daemons wait to 
communicate with one another to ensure they both understand the status of the
environment. This can either be done as part of the boot sequence using the
\fIclstart(1M)\fP utility, via the \fIclform(1M)\fP at any time, or be
direct invocation on hte command line [though this mode of invocation is
rarely used].

Please note that when attempting to 'form' the cluster using this 
command directly on the command lien - this command must be run on 
\fBboth\fP nodes that make up the cluster. 

If the intention is to start the process as part of the boot sequence 
it is recommended that consideration is given to the 
default timeout period in the cluster configuration file. Alternatively
use the \fIclstart(1M)\fP script with a suitable timeout for boot-up, or
override the default using the \fB--timeout\fP option described below.

.SH CLUSTER DAEMON PURPOSE
The cluster daemons are responsible for keeping track of the status of the
cluster. The utility commands used here query the local cluster daemon
when possible to validate certain conditions. For example if you attempt
to start a application 'apache' on 'serverb', the \fIclstartapp(1M)\fP
utility will communicate with the local server daemon to validate that
this application is not already running, either locally or remotely.

The cluster daemon is also responsible for handling application fail-over - 
when a hardware or software condition indicates that a particular application
should fail-over to the other node in the cluster, these daemons will take
the necessary actions and coordinate resources as appropriate.

The cluster daemon does not act alone. When it is started it will check
to see if all of the following daemons are running:

.TS
l .
* clnetd  - Linuxha.net Network Daemon
* cllockd - Linuxha.net Resource Locking Daemon
* clhbd   - Linuxha.net Heartbeat Daemon
.TE

If any of these other daemons are not running on the local machine
they will automatically be started with common arguments to ensure
they run verbosely as 'daemon' processes.

For more information on the specific daemons additional manual
pages for \fIclnetd(1M)\fP, \fIcllockd(1M)\fP and \fIclhbd(1M)\fP
should be consulted.

.SH JOINING A CLUSTER
If the cluster is currently operating on a single node and the remaining
node wishes to become part of the cluster - it must make use of the \fB--join\fP
argument to run in the 'Join' mode of operation. This is necessary following 
a hardware failure or when the administrator was specifically started the 
cluster on just a single node [for whatever reason]. 

When a node joins the cluster the other node in the cluster is responsible
for sending over messages indicating the status of the cluster to ensure
state information is synchronous for both nodes.

The time it takes for a node to join the cluster fully depends on the number of
messages that need to be sent - but typically this is just a few seconds. Only 
rarely has this taken more than 10 seconds.

Please note that the system times on both nodes in the cluster is
important. If the times are more than 10 minutes apart the node will fail 
to join the cluster unless the \fB--force\fP option has been specified. It should
be noted that this is the \fBsystem time\fP not the local time meaning that
nodes in different time zones should not present a problem.

.SH FORMING A CLUSTER
If the cluster is not currently running the \fB--form\fP argument should
be specified. When running in this mode then the process will wait for
some time sending out requests and responding to them to work through 
the process of establishing the cluster. 

The protocol used has been simplified for 1.2.0 though cluster formation can
still take as long as 10 seconds [though is typically less].

Again the times on both nodes in the cluster are considered and if 
more than 10 minutes apart [ignoring time zone information] will result in
the formation aborting unless the \fB--force\fP argument is specified.

.SH ARGUMENTS
The following arguments are supported. It should be noted that either
\fB--form\fP or \fB--join\fP should be specified, but not both!

.TP 8
.B --form
Indicates that the daemon should attempt to form a new cluster with the
other node in the cluster. It will wait a period of time for the other 
node to attempt to form a cluster before timing out. This timeout period
is defined in the cluster topology file but can be changed for this
invocation using the \fB--timeout\fP flag.
.TP
.B --join
This flag is used to indicate that the daemon should attempt to join
a cluster that has already been formed and is running. If the other node 
in the cluster is not currently running, or has started with \fB--form\fP
then this node will fail to become part of the cluster.
.TP
.B --verbose
Verbose mode - show progress messages to the defined log file. The default
location is defined in the cluster topology configuration file, but can be
modified using the \fB--file\fP option (see below).
.TP
.B --timeout
Override the maximum time to wait to join or form the cluster. After this 
period of time the action will be cancelled. After this period of time
the process will abort if \fB--join\fP has been specified - but if \fB--force\fP
has been specified along with \fB--form\fP then the cluster formation 
will complete with just this single node.
.TP
.B -F,--force
If you are attempting to form a cluster then this flag can be used to allow
the cluster to form with just one node. This option is purely defined to be
used by administrators when a node has failed and the cluster needs to start.
Placing this is flag in a boot sequence via the \fIclstart(1M)\fP tool is
strongly discouraged since it might cause the other server to fail to 
start correctly and not join the cluster at all.

The option is also used to allow the cluster to form, or a node to
join the cluster if the system time difference between the nodes is greater than 
10 minutes. As previously stated stated 
.TP
.B --file
Indicates the name of an alternative file to use to log messages, warnings
and errors to. This file defaults to the name given in the cluster topology
file but can be overridden if necessary. Other than giving it a file name '-'
can be specified for standard output and the current terminal can be
specified using '/dev/tty'.

Of course when starting a process as a daemon (which is recommended)
setting this is discouraged - leaving it to use default log files makes
administration easier.
.TP
.B --detach
This flag will cause the program to run as a daemon - this is recommended.
If this flag is not specified the program will run in the foreground
attached to the current terminal. That is useful for debugging, but generally
is not recommended for production-like environments. 

Both the high level utilities \fIclstart(1M)\fP and \fIclform(1M)\fP
make use of this facility.
.TP
.B --logcmd
This command is used typically for debugging purposes, but may be required
to be included if you have a problem that needs investigation. It will ensure
that when the verbose logging option is used all external commands issued
by the daemon are included in the log file generated.
.TP
.B --nolocking
Do not attempt to start a locking server on either host. It will also
respond to client requests for port information on the locking server
indicating that locking is not in use.

This flag should only really be used if the cluster is only managing a 
single application, or under advice from the developers.
.TP
.B --nochecksums
Normally if the cluster configuration file has been modified whilst the 
cluster is running the checksum which is used to indicate the last sane and 
checked configuration will not be valid. In such instances many of the 
Linuxha.net commands, including this will not will not function. 
If necessary the \fB--nochecksums\fP can be used to overcome this until the 
cluster configuration can be re-checked.
.TP
.B -C,--config
Specifies that the default configuration file used should not be used; 
instead use the file specified. This is typically used by the developers only.
.TP
.B -D,--debug
Run with debugging output. Will generate more information when the cluster
runs. This is only necessary when diagnosing faults can be ignored apart from
when requested to be used under advise of the developers.

.SH AUXILLARY DAEMONS
If the \fB--nolocking\fP flag is NOT used then the this process will also
start a locking daemon on each host. The locking daemon is responsible
for allocating advisory resource locks, and is strongly recommended 
if the cluster consists of more than one application.

If the locking daemon is already running it will be noted and no other
action taken. For more information on this daemon and the type of
locks it supports please see the \fIcllockd(1M)\fP manual page.

Similarly the network daemon will be started if necessary. This daemon
is vital to cluster functionality and thus can not be easily disabled for
obvious reasons! For more information on arguments please the the \fIclnetd(1M)zP
manual page.

Finally the Heartbeat daemon is started if not running. This monitors the
status of the other cluster and also sends out packets indicating the status
of the local host. For more information see the \fIclhbd(1M)\fP manual page.

.SH EXIT STATUS
The \fIcldaemon(1M)\fP utility makes use of many error codes, but in summary
it will return a non-zero number for an error or zero if the configuration
has been processed successfully.

If an error is generated many of the more obscure error conditions provide
several lines of information to help ensure the administrator is able to
resolve such problems as quickly as possible.

.SH FILES
The \fIcldaemon(1M)\fP process will only start if the following conditions
are met concerning the cluster topology file:

.TP 4
[1]
The topology file exists on both nodes that form the cluster, (unless 
the other node can not be contacted and the '--force' option has been
specified).
.TP
[2]
The checksum information for the topology file matches the current contents
of the topology file. If this is not the case it means that the cluster
configuration has been changed, but not yet validated via the \fIclbuild(1M)\fP
utility.
.RE

.TP 10
/etc/cluster/clconf.xml
This file contains the detailed cluster topology and must have been validated
on both machines prior to attempting to start the cluster daemon.
.TP
/var/log/cluster
This is the recommended directory where the cluster daemon writes its log
files. This can be changed but it is not recommended. The default name
of the configuration file is cldaemon-clustername.log.
.TP
/etc/cluster/APPNAME/appconf.xml
For each sub-directory in the /etc/cluster directory the daemon will check
for an 'appconf.xml' file and if found along with a matching checksums for
a validated configuration, the application will be registered with the cluster,
allowing it to be started via \fIclstartapp(1M)\fP or \fIclrunapp(1M)\fP.

.SH SEE ALSO
.TS
l l.
clbuild(1M)	- Build Cluster Topology
clbuildapp(1M)	- Build / Synchronise cluster application 
cldaemonctl(1M)	- Manage or query cluster daemon
clform(1M)	- High level cluster formation tool
clhaltapp(1M)	- Halt a clustered application
clhbd(1M)	- Cluster heartbeat daemon
cllockd(1M)	- Cluster locking daemon
clnetd(1M)	- Cluster network monitor daemon
clstat(1M)	- Show cluster status information
clstart(1M)	- Cluster formation on reboot tool
clstartapp(1M)	- Start a clustered application
clconf.xml(5)	- Overall cluster topology configuration file
appconf.xml(5)	- Configuration of an application used by the cluster
.TE

.SH NOTES
The Linuxha.net software has been designed so that if this \fIcldaemon(1M)\fP
process dies it does not leave the cluster in an unknown state. This situation
is explicitly catered for in the designed and restarting the daemon via the 
\fB--join\fP command line will allow the daemon to start and gain the cluster
status from the other daemon (if running).

If the other daemon does not appear to be running the daemon will attempt
to guess the status of all registered applications by checking the 
available IP addresses. If they are found activated on a host then it
is assumed that this host is running the application in question.

.SH AUTHOR
The \fIcldaemon(1M)\fP utility was written by Simon Edwards, 2003-2006. The
author can be contacted via the website mentioned below.

.SH AVAILABILITY
This software is freely available from the Linuxha.net website - please see
\fBhttp://www.linuxha.net\fP for more details.

.SH WARRANTY
This is Open Source Software is per the GNU GPL. It is free to use and
distribute but \fIcomes with no warranty whatsoever\fP. For more information
on the license please see \fBwww.gnu.org/copyleft/gpl.html\fP.

